<%
title = 'API overview'
description = "An overview of mountebank's RESTful API"
%>

<% include ../../_header %>

<h1>API Overview</h1>

<p>mountebank uses a basic REST style API with standard HTTP status codes. Every effort has
gone into providing <a href='/docs/api/errors'>response bodies</a> to help you diagnose the problems.
Each error response returned will have a <code>code</code> and <code>message</code> at a minimum.
If extra information is available, mountebank will happily pass it to you. If you get stuck,
email the group on the <a href='/support'>support page</a>, along with your logs, and mountebank
will happily assist you.</p>

<h2>Capabilities</h2>

<p>mountebank supports the following capabilities:</p>

<table>
  <tr>
    <th style='width: 25em;'>Capability</th>
    <th>Request Body</th>
    <th>Response Body</th>
  </tr>
  <tr>
    <td><a href='#get-home'>Get entry hypermedia</a></td>
    <td></td>
    <td><a href='/docs/api/contracts?type=home'>home</a></td>
  </tr>
  <tr>
    <td><a href='#post-imposters'>Create a single imposter</a></td>
    <td><a href='/docs/api/contracts?type=imposter'>imposter</a></td>
    <td><a href='/docs/api/contracts?type=imposter'>imposter</a></td>
  </tr>
  <tr>
    <td><a href='#get-imposter'>Get a single imposter</a></td>
    <td></td>
    <td><a href='/docs/api/contracts?type=imposter'>imposter</a></td>
  </tr>
  <tr>
    <td><a href='#add-stub'>Add a stub to an existing imposter</a></td>
    <td><a href='/docs/api/contracts?type=addStub'>add stub</a></td>
    <td><a href='/docs/api/contracts?type=imposter'>imposter</a></td>
  </tr>
  <tr>
    <td><a href='#change-stub'>Overwrite a stub of an existing imposter</a></td>
    <td><a href='/docs/api/contracts?type=stub'>stub</a></td>
    <td><a href='/docs/api/contracts?type=imposter'>imposter</a></td>
  </tr>
  <tr>
    <td><a href='#change-stubs'>Overwrite all stubs of an existing imposter</a></td>
    <td><a href='/docs/api/contracts?type=stubs'>stubs</a></td>
    <td><a href='/docs/api/contracts?type=imposter'>imposter</a></td>
  </tr>
  <tr>
    <td><a href='#delete-stub'>Remove a stub of an existing imposter</a></td>
    <td></td>
    <td><a href='/docs/api/contracts?type=imposter'>imposter</a></td>
  </tr>
  <tr>
    <td><a href='#delete-imposter'>Delete a single imposter</a></td>
    <td></td>
    <td><a href='/docs/api/contracts?type=imposter'>imposter</a></td>
  </tr>
  <tr>
    <td><a href='#delete-proxy-responses'>Delete saved proxy responses from an imposter</a></td>
    <td></td>
    <td></td>
  </tr>
  <tr>
    <td><a href='#delete-requests'>Delete saved requests from an imposter</a></td>
    <td></td>
    <td><a href='/docs/api/contracts?type=imposter'>imposter</a></td>
  </tr>
  <tr>
    <td><a href='#put-imposters'>Overwrite all imposters with a new set of imposters</a></td>
    <td><a href='/docs/api/contracts?type=imposters'>imposters</a></td>
    <td><a href='/docs/api/contracts?type=imposters'>imposters</a></td>
  </tr>
  <tr>
    <td><a href='#get-imposters'>Get a list of all imposters</a></td>
    <td></td>
    <td><a href='/docs/api/contracts?type=imposters'>imposters</a></td>
  </tr>
  <tr>
    <td><a href='#delete-imposters'>Delete all imposters</a></td>
    <td></td>
    <td><a href='/docs/api/contracts?type=imposters'>imposters</a></td>
  </tr>
  <tr>
    <td><a href='#get-config'>Get mountebank configuration and process information</a></td>
    <td></td>
    <td><a href='/docs/api/contracts?type=config'>config</a></td>
  </tr>
  <tr>
    <td><a href='#get-logs'>Get the logs</a></td>
    <td></td>
    <td><a href='/docs/api/contracts?type=logs'>logs</a></td>
  </tr>
</table>

<h3 id='get-home'>Get entry hypermedia</h3>

<pre><code>GET /</code></pre>

<p><b>Response contract</b>: <a href='/docs/api/contracts?type=home'>home</a></p>

<p>This endpoint exists for those who aspire to the
<a href='http://martinfowler.com/articles/richardsonMaturityModel.html'>upper echelons of REST</a>,
using hypermedia as the engine of application state. For those with more humble aspirations, mountebank
provides URL templates for all capabilities.</p>

<testScenario name='home'>
    <step type='http'>
<pre><code>GET / HTTP/1.1
Host: localhost:<%= port %>
Accept: application/json</code></pre>

        <assertResponse>
<pre><code>HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json; charset=utf-8
Content-Length: 226
Date: <volatile>Sun, 05 Jan 2014 16:16:08 GMT</volatile>
Connection: keep-alive

{
  "_links": {
    "imposters": { "href": "http://localhost:<%= port %>/imposters" },
    "config": { "href": "http://localhost:<%= port %>/config" },
    "logs": { "href": "http://localhost:<%= port %>/logs" }
  }
}</code></pre>
        </assertResponse>
    </step>
</testScenario>

<h3 id='post-imposters'>Create a single imposter</h3>

<pre><code>POST /imposters</code></pre>

<p><b>Request contract</b>: <a href='/docs/api/contracts?type=imposter'>imposter</a></p>
<p><b>Response contract</b>: <a href='/docs/api/contracts?type=imposter'>imposter</a></p>

<p>Though he's not proud to admit it, mountebank employs an army of imposters to
fulfill your orders.  Because your needs are varied and sundry, his imposters
are all different, and all are identified by a port number and associated with
a protocol.  The value you get out of mountebank always starts by creating an imposter,
which represents a test double listening on a socket.</p>

<p><strong>Parameters:</strong></p>

<p>If you don't need stubbing, then the port and protocol are all you need.  The parameters
each type of imposter accepts are explained on the page for the particular protocol
you're interested in.  See the protocols section on the sidebar on the left.</p>

<p>mountebank expects that you will be responsible for providing the
port, since you'll need to configure the application under test with the same
port.  However, the port is not required, and if you do not include it in the
request, mountebank will randomly assign one for you and return the port number
in the response.</p>

<testScenario name='imposters'>
    <step type='http'>
<pre><code>POST /imposters HTTP/1.1
Host: localhost:<%= port %>
Accept: application/json
Content-Type: application/json

{
  "port": 4545,
  "protocol": "http"
}</code></pre>

        <assertResponse>
<pre><code>HTTP/1.1 201 Created
Location: http://localhost:<%= port %>/imposters/4545
Content-Type: application/json; charset=utf-8
Content-Length: 298
Date: <volatile>Sun, 05 Jan 2014 16:28:40 GMT</volatile>
Connection: keep-alive

{
  "protocol": "http",
  "port": 4545,
  "numberOfRequests": 0,
  "recordRequests": false,
  "requests": [],
  "stubs": [],
  "_links": {
    "self": { "href": "http://localhost:<%= port %>/imposters/4545" },
    "stubs": { "href": "http://localhost:<%= port %>/imposters/4545/stubs" }
  }
}</code></pre>
        </assertResponse>
    </step>

<p>You can also initialize <a href='/docs/api/stubs'>stubs</a> in the <code>POST</code> call.</p>

<p>mountebank expects you to configure your application under test to point to the imposter. In
the case above, that would mean that your application has an http dependency configured to
http://localhost:4545. To retrieve a list of all imposters, simply issue a <code>GET</code>:</p>

<h3 id='get-imposter'>Get a single imposter</h3>

<pre><code>GET /imposters/:port</code></pre>

<p><b>Response contract</b>: <a href='/docs/api/contracts?type=imposter'>imposter</a></p>

<p>Retrieving an imposter is generally useful for one the following reasons:</p>

<ul class='bullet-list'>
  <li>You want to perform <a href='/docs/api/mocks'>mock verifications</a> by inspecting the
    <a href='/docs/api/mocks'><code>requests</code> array</a>).</li>
  <li>You want to debug <a href='/docs/api/predicates'>stub predicates</a> by inspecting the
    <a href='/docs/api/stubs#matches-array'><code>matches</code> array</a> (you must run
    <code>mb</code> with the <a href='/docs/commandLine'> <code>--debug</code> command line
      parameter</a> for this to work).</li>
  <li>You <a href='/docs/api/proxies'>proxied</a> a real service, and want to be save off the
    saved responses in a subsequent disconnected test run.</li>
</ul>

<p><strong>Query Parameters:</strong></p>

<table>
  <tr>
    <th>Name</th>
    <th>Type</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><code>replayable</code></td>
    <td>boolean</td>
    <td>Set to <code>true</code> to retrieve the minimum amount of information for
      <a href='#post-imposters'>creating the imposter</a> in the future.  This leaves
      out the <a href='/docs/api/mocks'><code>requests</code> array</a> and any hypermedia.</td>
  </tr>
  <tr>
    <td><code>removeProxies</code></td>
    <td>boolean</td>
    <td>Set to <code>true</code> to remove all proxy responses (and stubs) from the response.
      This is useful in record-playback scenarios where you want to seed the imposters with
      proxy information but leave it out on subsequent test runs.  You can
      <a href='#post-imposters'>recreate the imposter</a> in the future by using the response.</td>
  </tr>
</table>

    <step type='http'>
<pre><code>GET /imposters/4545 HTTP/1.1
Host: localhost:<%= port %>
Accept: application/json
</code></pre>

        <assertResponse>
<pre><code>HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json; charset=utf-8
Content-Length: 298
Date: <volatile>Sun, 05 Jan 2014 16:59:33 GMT</volatile>
Connection: keep-alive

{
  "protocol": "http",
  "port": 4545,
  "numberOfRequests": 0,
  "recordRequests": false,
  "requests": [],
  "stubs": [],
  "_links": {
    "self": { "href": "http://localhost:<%= port %>/imposters/4545" },
    "stubs": { "href": "http://localhost:<%= port %>/imposters/4545/stubs" }
  }
}</code></pre>
        </assertResponse>
    </step>

<p>Had we set the <code>replayable</code> query parameter, the
<a href='/docs/api/mocks'><code>requests</code> array</a> and
<code>_links</code> elements would not be there.  If we had any <a href='/docs/api/stubs'>stubs</a>,
the <a href='/docs/api/stubs#matches-array'><code>matches</code> array</a> would also not be present
regardless of whether we ran <code>mb</code> with the <code>--debug</code> command line parameter or
not. None of those fields are used during the creation of an imposter.</p>

    <step type='http'>
<pre><code>GET /imposters/4545?replayable=true HTTP/1.1
Host: localhost:<%= port %>
Accept: application/json</code></pre>

        <assertResponse>
<pre><code>HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json; charset=utf-8
Content-Length: 82
Date: <volatile>Sun, 05 Jan 2014 16:59:33 GMT</volatile>
Connection: keep-alive

{
  "protocol": "http",
  "port": 4545,
  "recordRequests": false,
  "stubs": []
}</code></pre>
        </assertResponse>
    </step>

<h3 id='add-stub'>Add a stub to an existing imposter</h3>

<p><b>Request contract</b>: <a href='/docs/api/contracts?type=addStub'>add stub</a></p>
<p><b>Response contract</b>: <a href='/docs/api/contracts?type=imposter'>imposter</a></p>

<pre><code>POST /imposters/:port/stubs</code></pre>

<p>In most cases, you would add the stubs at the time you create the imposter, but this call
allows you to add a stub to an existing imposter without restarting it. You can add the
new stub at any index between 0 and the end of the existing array. If you leave off the
<code>index</code> field, the stub will be added to the end of the existing <code>stubs</code>
array. On a successful request, mountebank will return the updated imposter resource.</p>

    <step type='http'>
<pre><code>POST /imposters/4545/stubs HTTP/1.1
Host: localhost:<%= port %>
Accept: application/json

{
  "index": 0,
  "stub": {
    "responses": [{
      "is": {
        "body": "Hello, world!"
      }
    }]
  }
}</code></pre>

        <assertResponse>
<pre><code>HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 548
Date: <volatile>Wed, 19 Jun 2019 01:00:55 GMT</volatile>
Connection: keep-alive

{
  "protocol": "http",
  "port": 4545,
  "numberOfRequests": 0,
  "recordRequests": false,
  "requests": [],
  "stubs": [{
    "responses": [{
      "is": {
        "body": "Hello, world!"
      }
    }],
    "_links": {
      "self": { "href": "http://localhost:<%= port %>/imposters/4545/stubs/0" }
    }
  }],
  "_links": {
    "self": { "href": "http://localhost:<%= port %>/imposters/4545" },
    "stubs": { "href": "http://localhost:<%= port %>/imposters/4545/stubs" }
  }
}</code></pre>
        </assertResponse>
    </step>

<h3 id='change-stub'>Change a stub in an existing imposter</h3>

<pre><code>PUT /imposters/:port/stubs/:stubIndex</code></pre>

<p><b>Request contract</b>: <a href='/docs/api/contracts?type=stub'>stub</a></p>
<p><b>Response contract</b>: <a href='/docs/api/contracts?type=imposter'>imposter</a></p>

<p>Use this endpoint to overwrite an existing stub without restarting the imposter. The
<code>stubIndex</code> must match the array index of the stub you wish to change. Pass
the new stub as the body of the request. The response will provide the updated imposter
resource.</p>

    <step type='http'>
<pre><code>PUT /imposters/4545/stubs/0 HTTP/1.1
Host: localhost:<%= port %>
Accept: application/json

{
  "responses": [{
    "is": {
      "body": "Goodbye, world!"
    }
  }]
}</code></pre>

        <assertResponse>
<pre><code>HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 550
Date: <volatile>Wed, 19 Jun 2019 01:00:55 GMT</volatile>
Connection: keep-alive

{
  "protocol": "http",
  "port": 4545,
  "numberOfRequests": 0,
  "recordRequests": false,
  "requests": [],
  "stubs": [{
    "responses": [{
      "is": {
        "body": "Goodbye, world!"
      }
    }],
    "_links": {
      "self": { "href": "http://localhost:<%= port %>/imposters/4545/stubs/0" }
    }
  }],
  "_links": {
    "self": { "href": "http://localhost:<%= port %>/imposters/4545" },
    "stubs": { "href": "http://localhost:<%= port %>/imposters/4545/stubs" }
  }
}</code></pre>
        </assertResponse>
    </step>

<h3 id='change-stubs'>Overwrite all stubs in an existing imposter</h3>

<pre><code>PUT /imposters/:port/stubs</code></pre>

<p><b>Request contract</b>: <a href='/docs/api/contracts?type=stubs'>stubs</a></p>
<p><b>Response contract</b>: <a href='/docs/api/contracts?type=imposter'>imposter</a></p>

<p>Use this endpoint to overwrite all existing stub without restarting the imposter. The
response will provide the updated imposter resource.</p>

    <step type='http'>
<pre><code>PUT /imposters/4545/stubs HTTP/1.1
Host: localhost:<%= port %>
Accept: application/json

{
  "stubs": [{
    "responses": [{
      "is": { "body": "New stub" }
    }]
  }]
}</code></pre>

        <assertResponse>
<pre><code>HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 543
Date: <volatile>Wed, 19 Jun 2019 01:00:55 GMT</volatile>
Connection: keep-alive

{
  "protocol": "http",
  "port": 4545,
  "numberOfRequests": 0,
  "recordRequests": false,
  "requests": [],
  "stubs": [
    {
      "responses": [{
        "is": { "body": "New stub" }
      }],
      "_links": {
        "self": { "href": "http://localhost:<%= port %>/imposters/4545/stubs/0" }
      }
    }
  ],
  "_links": {
    "self": { "href": "http://localhost:<%= port %>/imposters/4545" },
    "stubs": { "href": "http://localhost:<%= port %>/imposters/4545/stubs" }
  }
}</code></pre>
        </assertResponse>
    </step>

<h3 id='delete-stub'>Remove a single stub from an existing imposter</h3>

<pre><code>DELETE /imposters/:port/stubs/:stubIndex</code></pre>

<p><b>Response contract</b>: <a href='/docs/api/contracts?type=imposter'>imposter</a></p>

<p>Use this endpoint to remove the stub at the given array index without restarting the imposter. The
response will provide the updated imposter resource.</p>

    <step type='http'>
<pre><code>DELETE /imposters/4545/stubs/0 HTTP/1.1
Host: localhost:<%= port %>
Accept: application/json</code></pre>

        <assertResponse>
<pre><code>HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 298
Date: <volatile>Wed, 19 Jun 2019 01:00:55 GMT</volatile>
Connection: keep-alive

{
  "protocol": "http",
  "port": 4545,
  "numberOfRequests": 0,
  "recordRequests": false,
  "requests": [],
  "stubs": [],
  "_links": {
    "self": { "href": "http://localhost:<%= port %>/imposters/4545" },
    "stubs": { "href": "http://localhost:<%= port %>/imposters/4545/stubs" }
  }
}</code></pre>
        </assertResponse>
    </step>

<h3 id='delete-imposter'>Delete a single imposter</h3>

<pre><code>DELETE /imposters/:port</code></pre>

<p><b>Response contract</b>: <a href='/docs/api/contracts?type=imposter'>imposter</a></p>

<p>As mentioned above, typically you want to delete the imposter after each test run. This
frees up the socket and removes the resource. As a convenience, the <code>DELETE</code> call
also returns the imposter representation just like a <a href='#get-imposter'><code>GET</code> imposter</a>
would. This allows you to optimize the number of REST calls made during a test run when looking
at the <code>requests</code> array for <a href='/docs/api/mocks'>mock verification.</a><p>

<p><strong>Query Parameters:</strong></p>

<table>
  <tr>
    <th>Name</th>
    <th>Type</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><code>replayable</code></td>
    <td>boolean</td>
    <td>Set to <code>true</code> to retrieve the minimum amount of information for
      <a href='#post-imposters'>creating the imposter</a> in the future.  This leaves
      out the <a href='/docs/api/mocks'><code>requests</code> array</a> and any hypermedia.</td>
  </tr>
  <tr>
    <td><code>removeProxies</code></td>
    <td>boolean</td>
    <td>Set to <code>true</code> to remove all proxy responses (and stubs) from the response.
      This is useful in record-playback scenarios where you want to seed the imposters with
      proxy information but leave it out on subsequent test runs.  You can
      <a href='#post-imposters'>recreate the imposter</a> in the future by using the response.</td>
  </tr>
</table>

    <step type='http'>
<pre><code>DELETE /imposters/4545 HTTP/1.1
Host: localhost:<%= port %>
Accept: application/json</code></pre>

        <assertResponse>
<pre><code>HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 298
Date: <volatile>Sun, 05 Jan 2014 16:59:33 GMT</volatile>
Connection: keep-alive

{
  "protocol": "http",
  "port": 4545,
  "numberOfRequests": 0,
  "recordRequests": false,
  "requests": [],
  "stubs": [],
  "_links": {
    "self": { "href": "http://localhost:<%= port %>/imposters/4545" },
    "stubs": { "href": "http://localhost:<%= port %>/imposters/4545/stubs" }
  }
}
</code></pre>
        </assertResponse>
    </step>

<h3 id='delete-proxy-responses'>Delete saved proxy responses from an imposter</h3>

<pre><code>DELETE /imposters/:port/savedProxyResponses</code></pre>

<p><a href='/docs/api/proxies'>Proxy stubs</a> save all responses returned from downstream systems. Usually
this is what you want, as they can be played back at a later time without the actual downstream system
available. However, if you need to clear them but keep the stubs intact, you can do so with this call.<p>

<p class='info-icon'>Note that you can prevent the proxy from saving responses by setting the <code>mode</code>
to <a href='/docs/api/proxies#proxy-modes'><code>proxyTransparent</code></a>.</p>

<h3 id='delete-requests'>Delete saved requests from an imposter</h3>

<pre><code>DELETE /imposters/:port/savedRequests</code></pre>

<p><b>Response contract</b>: <a href='/docs/api/contracts?type=imposter'>imposter</a></p>

<p>Clear an imposter's recorded requests (used for <a href='/docs/api/mocks'>mock verification</a>) while leaving the rest of the imposter intact.
On a successful request, mountebank will return the updated imposter resource.</p>

<h3 id='put-imposters'>Overwrite all imposters with a new set of imposters</h3>

<pre><code>PUT /imposters</code></pre>

<p><b>Request contract</b>: <a href='/docs/api/contracts?type=imposters'>imposters</a></p>
<p><b>Response contract</b>: <a href='/docs/api/contracts?type=imposters'>imposters</a></p>

<p>Sometimes you want to create a batch of imposters in a single call, overwriting
any imposters already created.  This call is destructive - it will first delete all
existing imposters. The output of a <code>GET /imposters?replayable=true</code> can
directly be replayed through this call. This call is also used during startup
if you set the <code>--configfile</code> <a href='/docs/commandLine'>command line</a>
flag.</p>

<p><strong>Parameters:</strong></p>

<p>You must provide mountebank an <code>imposters</code> array.  Each element in the
array is the same as what's needed to <a href='#post-imposters'>create a single imposter</a>,
the parameters for which vary by protocol.  View the protocol pages on the left for details.</p>

    <step type='http'>
<pre><code>PUT /imposters HTTP/1.1
Host: localhost:<%= port %>
Content-Type: application/json

{
  "imposters": [
    {
      "protocol": "http",
      "port": 4546
    },
    {
      "protocol": "tcp",
      "port": 4547,
      "mode": "binary"
    },
    {
      "protocol": "smtp",
      "port": 4548
    }
  ]
}</code></pre>

        <assertResponse>
<pre><code>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 898
Date: <volatile>Sun, 05 Jan 2014 16:59:33 GMT</volatile>
Connection: keep-alive

{
  "imposters": [
    {
      "protocol": "http",
      "port": 4546,
      "numberOfRequests": 0,
      "_links": {
        "self": { "href": "http://localhost:<%= port %>/imposters/4546" },
        "stubs": { "href": "http://localhost:<%= port %>/imposters/4546/stubs" }
      }
    },
    {
      "protocol": "tcp",
      "port": 4547,
      "numberOfRequests": 0,
      "_links": {
        "self": { "href": "http://localhost:<%= port %>/imposters/4547" },
        "stubs": { "href": "http://localhost:<%= port %>/imposters/4547/stubs" }
      }
    },
    {
      "protocol": "smtp",
      "port": 4548,
      "numberOfRequests": 0,
      "_links": {
        "self": { "href": "http://localhost:<%= port %>/imposters/4548" },
        "stubs": { "href": "http://localhost:<%= port %>/imposters/4548/stubs" }
      }
    }
  ]
}</code></pre>
        </assertResponse>
    </step>

<h3 id='get-imposters'>Get a list of all imposters</h3>

<pre><code>GET /imposters</code></pre>

<p><b>Response contract</b>: <a href='/docs/api/contracts?type=imposters'>imposters</a></p>

<p>This is where you will come to retrieve a list of all active imposters.  By default,
mountebank returns some basic information and hypermedia.  If you want more information,
either <a href='#get-imposter'>get the single imposter</a> or use the
<code>replayable</code> flag.</p>

<p><strong>Query Parameters:</strong></p>

<table>
  <tr>
    <th>Name</th>
    <th>Type</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><code>replayable</code></td>
    <td>boolean</td>
    <td>Set to <code>true</code> to retrieve the minimum amount of information for replaying
      the set of imposters in the future through a <a href='#put-imposters'>mass create</a>
      call.  This leaves out the <a href='/docs/api/mocks'><code>requests</code> array</a>
      and any hypermedia.</td>
  </tr>
  <tr>
    <td><code>removeProxies</code></td>
    <td>boolean</td>
    <td>Set to <code>true</code> to remove all proxy responses (and stubs) from the response.
      This is useful in record-playback scenarios where you want to seed the imposters with
      proxy information but leave it out on subsequent test runs.  You can
      <a href='#put-imposters'>recreate the imposter</a> in the future by using the response.</td>
  </tr>
</table>

    <step type='http'>
<pre><code>GET /imposters HTTP/1.1
Host: localhost:<%= port %>
Accept: application/json</code></pre>

        <assertResponse>
<pre><code>HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json; charset=utf-8
Content-Length: 898
Date: <volatile>Sun, 05 Jan 2014 16:58:25 GMT</volatile>
Connection: keep-alive

{
  "imposters": [
    {
      "protocol": "http",
      "port": 4546,
      "numberOfRequests": 0,
      "_links": {
        "self": { "href": "http://localhost:<%= port %>/imposters/4546" },
        "stubs": { "href": "http://localhost:<%= port %>/imposters/4546/stubs" }
      }
    },
    {
      "protocol": "tcp",
      "port": 4547,
      "numberOfRequests": 0,
      "_links": {
        "self": { "href": "http://localhost:<%= port %>/imposters/4547" },
        "stubs": { "href": "http://localhost:<%= port %>/imposters/4547/stubs" }
      }
    },
    {
      "protocol": "smtp",
      "port": 4548,
      "numberOfRequests": 0,
      "_links": {
        "self": { "href": "http://localhost:<%= port %>/imposters/4548" },
        "stubs": { "href": "http://localhost:<%= port %>/imposters/4548/stubs" }
      }
    }
  ]
}</code></pre>
        </assertResponse>
    </step>

<h3 id='delete-imposters'>Delete all imposters</h3>

<pre><code>DELETE /imposters</code></pre>

<p><b>Response contract</b>: <a href='/docs/api/contracts?type=imposters'>imposters</a></p>

<p>The surest way to reset to a clean slate is to delete all imposters. Any imposter sockets
mountebank has open will be closed, and the response body will contain exactly what you need
to <a href='#put-imposters'>mass create</a> the same imposters in the future.</p>

<p><strong>Query Parameters:</strong></p>

<table>
  <tr>
    <th>Name</th>
    <th>Type</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><code>replayable</code></td>
    <td>boolean</td>
    <td>Defaults to true.  Set to <code>false</code> to retrieve the
      <a href='/docs/api/mocks'><code>requests</code></a> arrays with the response.  You can still
      <a href='#put-imposters'>mass create</a> using this JSON; it just has extraneous information.</td>
  </tr>
  <tr>
    <td><code>removeProxies</code></td>
    <td>boolean</td>
    <td>Set to <code>true</code> to remove all proxy responses (and stubs) from the response.
      This is useful in record-playback scenarios where you want to seed the imposters with
      proxy information but leave it out on subsequent test runs.  You can
      <a href='#put-imposters'>recreate the imposters</a> in the future by using the response.</td>
  </tr>
</table>

    <step type='http'>
<pre><code>DELETE /imposters HTTP/1.1
Host: localhost:<%= port %>
Accept: application/json</code></pre>

        <assertResponse>
<pre><code>HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 370
Date: <volatile>Sun, 05 Jan 2014 16:58:25 GMT</volatile>
Connection: keep-alive

{
  "imposters": [
    {
      "protocol": "http",
      "port": 4546,
      "recordRequests": false,
      "stubs": []
    },
    {
      "protocol": "tcp",
      "port": 4547,
      "recordRequests": false,
      "mode": "binary",
      "stubs": []
    },
    {
      "protocol": "smtp",
      "port": 4548,
      "recordRequests": false,
      "stubs": []
    }
  ]
}</code></pre>
        </assertResponse>
    </step>

<h3 id='get-config'>Get mountebank configuration and process information</h3>

<pre><code>GET /config</code></pre>

<p><b>Response contract</b>: <a href='/docs/api/contracts?type=config'>config</a></p>

<p>If you want to know about the environment mountebank is running it, this resource will give you
what you need.  It describes the version, command line flags, and process information.</p>

    <step type='http'>
<pre><code>GET /config HTTP/1.1
Host: localhost:<%= port %>
Accept: application/json</code></pre>

        <assertResponse>
<pre><code>HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json; charset=utf-8
Content-Length: <volatile>550</volatile>
Date: <volatile>Sat, 13 May 2017 23:41:31 GMT</volatile>
Connection: keep-alive

{
  "version": "<%= version %>",
  "options": {
    "port": <%= port %>,
    "pidfile": "mb.pid",
    "allowInjection": true,
    "mock": true,
    "localOnly": true, <% if (process.env.MB_PERSISTENT === 'true') { %>
    "datadir": ".mbdb", <% } %>
    "noParse": false,
    "formatter": "mountebank-formatters",
    "ipWhitelist": [
      "*"
    ],
    "debug": false,
    "protofile": "protocols.json",
    "origin": false,
    "log": {
      "level": "info",
      "transports": {
        "console": {
          "colorize": true,
          "format": "%level: %message"
        },
        "file": {
          "path": "mb.log",
          "format": "json"
        }
      }
    }
  },
  "process": {
    "nodeVersion": "<volatile>v5.8.0</volatile>",
    "architecture": "<volatile>x64</volatile>",
    "platform": "<volatile>darwin</volatile>",
    "rss": <volatile>43393024</volatile>,
    "heapTotal": <volatile>32266016</volatile>,
    "heapUsed": <volatile>20060904</volatile>,
    "uptime": <volatile>69.108</volatile>,
    "cwd": "<volatile>/Users/bbyars/src/mountebank</volatile>"
  }
}</code></pre>
        </assertResponse>
    </step>

<h3 id='get-logs'>Get the logs</h3>

<pre><code>GET /logs</code></pre>

<p><b>Response contract</b>: <a href='/docs/api/contracts?type=logs'>logs</a></p>

<p><strong>Query Parameters:</strong></p>

<table>
  <tr>
    <th>Name</th>
    <th>Type</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><code>startIndex</code></td>
    <td>integer</td>
    <td>Set to array index of the first log entry you want returned.</td>
  </tr>
  <tr>
    <td><code>endIndex</code></td>
    <td>integer</td>
    <td>Set to the array index of the last log entry you want returned</td>
  </tr>
</table>

    <step type='http'>
<pre><code>GET /logs?startIndex=0&endIndex=1 HTTP/1.1
Host: localhost:<%= port %>
Accept: application/json</code></pre>

        <assertResponse>
<pre><code>HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json; charset=utf-8
Content-Length: <volatile>5249</volatile>
Date: <volatile>Sat, 13 May 2017 23:45:07 GMT</volatile>
Connection: keep-alive

{
  "logs": [
    {
      "message": "[mb:<%= port %>] Running with --allowInjection set. See http://localhost:<%= port %>/docs/security for security info",
      "level": "warn",
      "timestamp": "<volatile>2015-10-20T03:33:23.019Z</volatile>"
    },
    {
      "message": "[mb:<%= port %>] mountebank v<%= version %> now taking orders - point your browser to http://localhost:<%= port %>/ for help",
      "level": "info",
      "timestamp": "<volatile>2015-10-20T03:33:23.018Z</volatile>"
    }
  ]
}</code></pre>
        </assertResponse>
    </step>
</testScenario>

<p>In the rare scenario where mountebank is hosted on a different server and you need access to the logs,
they are accessible through this endpoint.</p>

<% include ../../_footer %>
